Package com.netscape.cmstools

Class hsmCompatVerifyServ

java.lang.Object

com.netscape.cmstools.hsmCompatVerifyServ

public class hsmCompatVerifyServ
extends Object

KRA HSM/PKCS#11 Compatibility Verification Tool This tool verifies the minimum capabilities required for KRA key archival and recovery operations without requiring a full PKI installation. Two-phase operation: 1. Setup Phase (--setup-only): Creates CA/KRA certificates on HSM - CA signing certificate (self-signed) - KRA transport certificate (signed by CA) - KRA storage certificate (signed by CA) 2. Verification Phase: Verifies complete archival/recovery workflow - Generate user key on client token - Archive using transport key (HSM) - Store using storage key (HSM) - Recover using storage key (HSM) - Create PKCS#12 This verifies essential PKCS#11 mechanisms: HSM: - RSA or EC key pair generation (for CA cert) - RSA key pair generation (for transport/storage certs, required for key wrapping) - Self-signed certificate creation - Certificate signing - RSA key wrapping/unwrapping (with optional OAEP support) - Session key (AES) generation and operations Client token: - RSA or EC key pair generation (user keys) - Symmetric key wrapping/unwrapping Note: KRA transport and storage certificates must be RSA for key wrapping operations. CA and user certificates can be RSA or EC. Code references (mimicing the real PKI operations): - Client-side wrapping: base/tools/src/main/java/com/netscape/cmstools/CRMFPopClient.java - KRA archival: base/kra/src/main/java/com/netscape/kra/EnrollmentService.java - KRA recovery: base/kra/src/main/java/com/netscape/kra/RecoveryService.java - Transport key ops: base/kra/src/main/java/com/netscape/kra/TransportKeyUnit.java - Storage key ops: base/kra/src/main/java/com/netscape/kra/StorageKeyUnit.java

Author:

Christina Fu (cfu)

Field Summary

Fields

Modifier and Type	Field	Description
static final String	TOOL_NAME
boolean	verbose

Constructor Summary

Constructors

Constructor	Description
hsmCompatVerifyServ()

Method Summary

Modifier and Type	Method	Description
static org.apache.commons.cli.Options	createOptions()
static void	main(String[] args)
static void	printError(String message)
static void	printHelp()
void	runIssueCsr(String pkiservDB, String pkiservPasswd, String caToken, String caTokenPasswd, String caNickname, String csrFile, boolean pqcMode)	Issue CSR Mode - Sign a CSR using existing CA on HSM Loads the CA certificate and private key from the HSM, reads a CSR from file, signs it, and writes the signed certificate to an output file.
void	runSetup(String pkiservDB, String pkiservPasswd, String hsmToken, String hsmTokenPasswd, String caToken, String caTokenPasswd, String kraToken, String kraTokenPasswd, String caKeyAlgorithm, String caKeySize, String caSubject, int caValidity, String caNickname, String transportSubject, int transportValidity, String transportNickname, String transportOpFlagsStr, String transportOpFlagsMaskStr, String storageSubject, int storageValidity, String storageNickname, String storageOpFlagsStr, String storageOpFlagsMaskStr, boolean caOnly)	Setup phase: Creates PKI infrastructure on HSM Creates three certificate/key pairs on the HSM: 1.
void	runSetupPQC(String pkiservDB, String pkiservPasswd, String hsmToken, String hsmTokenPasswd, String caToken, String caTokenPasswd, String kraToken, String kraTokenPasswd, String pqcCaAlgorithm, String pqcKemAlgorithm, String caSubject, int caValidity, String caNickname, String transportSubject, int transportValidity, String transportNickname, String storageSubject, int storageValidity, String storageNickname, boolean caOnly)	PQC Setup Phase - Creates ML-DSA CA and ML-KEM KRA certificates Creates three certificate/key pairs on the HSM: 1.
void	runTest(String pkiservDB, String clientDB, String wrappedSessionFile, String wrappedPrivateFile, String publicKeyFile, String ivFile, String caToken, String caTokenPasswd, String kraToken, String kraTokenPasswd, String caNickname, String transportNickname, String storageNickname, String subjectDN, String outputFile, String recoveryPasswd, String keywrapAlg, boolean archiveOnly, boolean recoverOnly, String ldifFile, String pkcs12Mode)	Test phase: Runs archival and/or recovery workflow This method supports three modes: 1.
void	runTestPQC(String pkiservDB, String clientDB, String kemCiphertextFile, String wrappedPrivateFile, String publicKeyFile, String caToken, String caTokenPasswd, String kraToken, String kraTokenPasswd, String caNickname, String transportNickname, String storageNickname, String subjectDN, String outputFile, String recoveryPasswd, String keywrapAlg, boolean archiveOnly, boolean recoverOnly, String ldifFile, String pkcs12Mode, String userKeyType, String kemAlgorithm)	Test phase for PQC (ML-KEM): Runs archival workflow with ML-KEM encapsulation This method performs ML-KEM-based key archival: 1.
void	setAutoYes(boolean autoYes)
void	setUseOAEP(boolean useOAEP)
void	setVerbose(boolean verbose)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details

TOOL_NAME

public static final String TOOL_NAME

See Also:

• Constant Field Values

verbose

public boolean verbose

Constructor Details

hsmCompatVerifyServ

public hsmCompatVerifyServ()

Method Details

createOptions

public static org.apache.commons.cli.Options createOptions()

printHelp

public static void printHelp()

printError

public static void printError(String message)

main

public static void main(String[] args)
                 throws Exception

Throws:

Exception

setVerbose

public void setVerbose(boolean verbose)

setUseOAEP

public void setUseOAEP(boolean useOAEP)

setAutoYes

public void setAutoYes(boolean autoYes)

runSetup

public void runSetup(String pkiservDB,
 String pkiservPasswd,
 String hsmToken,
 String hsmTokenPasswd,
 String caToken,
 String caTokenPasswd,
 String kraToken,
 String kraTokenPasswd,
 String caKeyAlgorithm,
 String caKeySize,
 String caSubject,
 int caValidity,
 String caNickname,
 String transportSubject,
 int transportValidity,
 String transportNickname,
 String transportOpFlagsStr,
 String transportOpFlagsMaskStr,
 String storageSubject,
 int storageValidity,
 String storageNickname,
 String storageOpFlagsStr,
 String storageOpFlagsMaskStr,
 boolean caOnly)
              throws Exception

Setup phase: Creates PKI infrastructure on HSM Creates three certificate/key pairs on the HSM: 1. CA signing certificate (self-signed) 2. KRA transport certificate (signed by CA) 3. KRA storage certificate (signed by CA) Also stores public certificates in PKI server NSS DB for reference. Adopted from various PKI cert generation utilities, but simplified for testing.

Throws:

Exception

runSetupPQC

public void runSetupPQC(String pkiservDB,
 String pkiservPasswd,
 String hsmToken,
 String hsmTokenPasswd,
 String caToken,
 String caTokenPasswd,
 String kraToken,
 String kraTokenPasswd,
 String pqcCaAlgorithm,
 String pqcKemAlgorithm,
 String caSubject,
 int caValidity,
 String caNickname,
 String transportSubject,
 int transportValidity,
 String transportNickname,
 String storageSubject,
 int storageValidity,
 String storageNickname,
 boolean caOnly)
                 throws Exception

PQC Setup Phase - Creates ML-DSA CA and ML-KEM KRA certificates Creates three certificate/key pairs on the HSM: 1. CA signing certificate with ML-DSA (self-signed) 2. KRA transport certificate with ML-KEM (signed by CA) 3. KRA storage certificate with ML-KEM (signed by CA) Also stores public certificates in PKI server NSS DB for reference.

Throws:

Exception

runIssueCsr

public void runIssueCsr(String pkiservDB,
 String pkiservPasswd,
 String caToken,
 String caTokenPasswd,
 String caNickname,
 String csrFile,
 boolean pqcMode)
                 throws Exception

Issue CSR Mode - Sign a CSR using existing CA on HSM Loads the CA certificate and private key from the HSM, reads a CSR from file, signs it, and writes the signed certificate to an output file.

Parameters:

pkiservDB - Path to PKI server NSS database

pkiservPasswd - Password for PKI server NSS database

caToken - CA token name (token where CA signing key resides)

caTokenPasswd - CA token password

caNickname - CA certificate nickname on CA token

csrFile - Path to CSR file (PEM format)

pqcMode - Whether CA uses PQC (ML-DSA) or traditional (RSA/EC)

Throws:

Exception

runTest

public void runTest(String pkiservDB,
 String clientDB,
 String wrappedSessionFile,
 String wrappedPrivateFile,
 String publicKeyFile,
 String ivFile,
 String caToken,
 String caTokenPasswd,
 String kraToken,
 String kraTokenPasswd,
 String caNickname,
 String transportNickname,
 String storageNickname,
 String subjectDN,
 String outputFile,
 String recoveryPasswd,
 String keywrapAlg,
 boolean archiveOnly,
 boolean recoverOnly,
 String ldifFile,
 String pkcs12Mode)
             throws Exception

Test phase: Runs archival and/or recovery workflow This method supports three modes: 1. Archival only (archiveOnly=true): Archive keys to LDIF and stop 2. Recovery only (recoverOnly=true): Read from LDIF and recover to PKCS#12 3. Combined (neither flag): Full archival+recovery workflow (creates LDIF + recovers to PKCS#12) Adopted from: CRMFPopClient, EnrollmentService, RecoveryService, TransportKeyUnit, StorageKeyUnit (see detailed comments inline)

Parameters:

pkiservDB - PKI system NSS database path - REQUIRED for HSM access. CryptoManager must be initialized with this database because it contains the modutil configuration that loads the HSM PKCS#11 module. Without this, the HSM token won't be found.

clientDB - Client NSS database directory (base path for wrapped key files and p12 output)

wrappedSessionFile - Wrapped session key file (from hsmCompatVerifyClnt, null for recovery mode)

wrappedPrivateFile - Wrapped private key file (from hsmCompatVerifyClnt, null for recovery mode)

publicKeyFile - Public key file in DER format (from hsmCompatVerifyClnt, null for recovery mode)

archiveOnly - If true, create LDIF and stop (archival only mode, no recovery)

recoverOnly - If true, read from existing LDIF file (recovery only mode, no archival)

ldifFile - LDIF file path for archival output or recovery input

Throws:

Exception

runTestPQC

public void runTestPQC(String pkiservDB,
 String clientDB,
 String kemCiphertextFile,
 String wrappedPrivateFile,
 String publicKeyFile,
 String caToken,
 String caTokenPasswd,
 String kraToken,
 String kraTokenPasswd,
 String caNickname,
 String transportNickname,
 String storageNickname,
 String subjectDN,
 String outputFile,
 String recoveryPasswd,
 String keywrapAlg,
 boolean archiveOnly,
 boolean recoverOnly,
 String ldifFile,
 String pkcs12Mode,
 String userKeyType,
 String kemAlgorithm)
                throws Exception

Test phase for PQC (ML-KEM): Runs archival workflow with ML-KEM encapsulation This method performs ML-KEM-based key archival: 1. Decapsulate KEM ciphertext with transport private key → recover shared secret 2. Unwrap user private key with shared secret 3. Re-encapsulate with storage public key → new shared secret 4. Wrap user private key with new shared secret 5. Generate LDIF for archival

Parameters:

pkiservDB - PKI system NSS database path (for HSM access)

clientDB - Client NSS database directory (base path for wrapped key files)

kemCiphertextFile - KEM ciphertext file (from hsmCompatVerifyClnt --pqc)

wrappedPrivateFile - Wrapped private key file (from hsmCompatVerifyClnt --pqc)

publicKeyFile - Public key file in DER format (ML-KEM public key)

caNickname - CA certificate nickname

transportNickname - Transport certificate nickname

storageNickname - Storage certificate nickname

subjectDN - Subject DN for user certificate

outputFile - Output PKCS#12 file (for future recovery testing)

recoveryPasswd - PKCS#12 password

keywrapAlg - Key wrap algorithm (AES-KWP)

archiveOnly - If true, create LDIF and stop (archival only mode)

ldifFile - LDIF file path for archival output

pkcs12Mode - PKCS#12 encryption mode: - "kwp": PBES2 with AES-KWP (default, FIPS-compliant) - "cbc": PBES2 with AES-CBC (FIPS-compliant) - "legacy": PBES1 with DES3-CBC (not recommended for FIPS)

kemAlgorithm - ML-KEM algorithm (ml-kem-512/768/1024)

hsmToken - HSM token name

hsmTokenPasswd - HSM token password

Throws:

Exception